<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.5"/>
<title>Theron: Theron::Actor::RegisterHandler</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/search.js"></script>
<script type="text/javascript">
  $(document).ready(function() { searchBox.OnSelectItem(0); });
</script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td style="padding-left: 0.5em;">
   <div id="projectname">Theron
   &#160;<span id="projectnumber">6.00.02</span>
   </div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.5 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search",false,'Search');
</script>
  <div id="navrow1" class="tabs">
    <ul class="tablist">
      <li><a href="index.html"><span>Main&#160;Page</span></a></li>
      <li><a href="namespaces.html"><span>Namespaces</span></a></li>
      <li><a href="annotated.html"><span>Classes</span></a></li>
      <li><a href="files.html"><span>Files</span></a></li>
      <li>
        <div id="MSearchBox" class="MSearchBoxInactive">
        <span class="left">
          <img id="MSearchSelect" src="search/mag_sel.png"
               onmouseover="return searchBox.OnSearchSelectShow()"
               onmouseout="return searchBox.OnSearchSelectHide()"
               alt=""/>
          <input type="text" id="MSearchField" value="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)" 
               onblur="searchBox.OnSearchFieldFocus(false)" 
               onkeyup="searchBox.OnSearchFieldChange(event)"/>
          </span><span class="right">
            <a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a>
          </span>
        </div>
      </li>
    </ul>
  </div>
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
<a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(0)"><span class="SelectionMark">&#160;</span>All</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(1)"><span class="SelectionMark">&#160;</span>Classes</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(2)"><span class="SelectionMark">&#160;</span>Namespaces</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(3)"><span class="SelectionMark">&#160;</span>Files</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(4)"><span class="SelectionMark">&#160;</span>Functions</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(5)"><span class="SelectionMark">&#160;</span>Variables</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(6)"><span class="SelectionMark">&#160;</span>Typedefs</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(7)"><span class="SelectionMark">&#160;</span>Enumerations</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(8)"><span class="SelectionMark">&#160;</span>Enumerator</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(9)"><span class="SelectionMark">&#160;</span>Macros</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(10)"><span class="SelectionMark">&#160;</span>Pages</a></div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

<div id="nav-path" class="navpath">
  <ul>
<li class="navelem"><a class="el" href="namespaceTheron.html">Theron</a></li><li class="navelem"><a class="el" href="classTheron_1_1Actor.html">Actor</a></li>  </ul>
</div>
</div><!-- top -->
<div class="contents">
<table cellspacing="0" cellpadding="0" border="0">
  <tr>
   <td valign="top">
      <div class="navtab">
        <table>
          <tr><td class="navtab"><a class="qindex" href="classTheron_1_1Actor_a87c458ad24c3429da325ea6f207267f4.html#a87c458ad24c3429da325ea6f207267f4">Actor</a></td></tr>
          <tr><td class="navtab"><a class="qindex" href="classTheron_1_1Actor_a3da98155747d33d767fe12b8b8c13aac.html#a3da98155747d33d767fe12b8b8c13aac">DeregisterHandler</a></td></tr>
          <tr><td class="navtab"><a class="qindex" href="classTheron_1_1Actor_a268613b27d2d718b55e2eb489118aa04.html#a268613b27d2d718b55e2eb489118aa04">GetAddress</a></td></tr>
          <tr><td class="navtab"><a class="qindex" href="classTheron_1_1Actor_afe30f86e99ff80691ec11e207711a46a.html#afe30f86e99ff80691ec11e207711a46a">GetFramework</a></td></tr>
          <tr><td class="navtab"><a class="qindex" href="classTheron_1_1Actor_a4f6af5dba4b36bbb55ee216589ccfb63.html#a4f6af5dba4b36bbb55ee216589ccfb63">GetNumQueuedMessages</a></td></tr>
          <tr><td class="navtab"><a class="qindex" href="classTheron_1_1Actor_a8b85886531b76f0e6aa9b46004ff6bb0.html#a8b85886531b76f0e6aa9b46004ff6bb0">IsHandlerRegistered</a></td></tr>
          <tr><td class="navtab"><a class="qindexHL" href="classTheron_1_1Actor_a8d5ef774be6470b8a1e8159f93aac07a.html#a8d5ef774be6470b8a1e8159f93aac07a">RegisterHandler</a></td></tr>
          <tr><td class="navtab"><a class="qindex" href="classTheron_1_1Actor_a47c64d58a7a683b34101002989d7de0a.html#a47c64d58a7a683b34101002989d7de0a">Send</a></td></tr>
          <tr><td class="navtab"><a class="qindex" href="classTheron_1_1Actor_a752faea0ecbb7f9525c02ed1ef19cbaf.html#a752faea0ecbb7f9525c02ed1ef19cbaf">SetDefaultHandler</a></td></tr>
          <tr><td class="navtab"><a class="qindex" href="classTheron_1_1Actor_ab8806dfed72869b22d966968340268c3.html#ab8806dfed72869b22d966968340268c3">SetDefaultHandler</a></td></tr>
          <tr><td class="navtab"><a class="qindex" href="classTheron_1_1Actor_a8ad74c59dded739fd71a66b96bc79ea8.html#a8ad74c59dded739fd71a66b96bc79ea8">TailSend</a></td></tr>
          <tr><td class="navtab"><a class="qindex" href="classTheron_1_1Actor_a95ce244d6cd6f4f3bfaea29dfb89ab6c.html#a95ce244d6cd6f4f3bfaea29dfb89ab6c">~Actor</a></td></tr>
        </table>
      </div>
   </td>
   <td valign="top" class="mempage">
<a class="anchor" id="a8d5ef774be6470b8a1e8159f93aac07a"></a>
<div class="memitem">
<div class="memproto">
<div class="memtemplate">
template&lt;class ActorType , class ValueType &gt; </div>
<table class="mlabels">
  <tr>
  <td class="mlabels-left">
      <table class="memname">
        <tr>
          <td class="memname">bool Theron::Actor::RegisterHandler </td>
          <td>(</td>
          <td class="paramtype">ActorType *const&#160;</td>
          <td class="paramname"><em>actor</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">void(ActorType::*)(const ValueType &amp;message, const <a class="el" href="classTheron_1_1Address.html">Address</a> from)&#160;</td>
          <td class="paramname"><em>handler</em>&#160;</td>
        </tr>
        <tr>
          <td></td>
          <td>)</td>
          <td></td><td></td>
        </tr>
      </table>
  </td>
  <td class="mlabels-right">
<span class="mlabels"><span class="mlabel">inline</span><span class="mlabel">protected</span></span>  </td>
  </tr>
</table>
</div><div class="memdoc">

<p>Registers a handler for a specific message type. </p>
<p>Derived actor classes should call this method to register message handlers. Once registered, a message handler is automatically executed whenever the owning actor receives a message of the type that the message handler function accepts.</p>
<p>For example this simple HelloWorld actor has a single handler which is executed in response to <em>hello</em> messages. It's important to note that message handlers must currently always take their message parameters by <em>reference:</em> </p>
<div class="fragment"><div class="line"><span class="keyword">class </span>HelloWorld : <span class="keyword">public</span> <a class="code" href="classTheron_1_1Actor.html">Theron::Actor</a></div>
<div class="line">{</div>
<div class="line"><span class="keyword">public</span>:</div>
<div class="line"></div>
<div class="line">    <span class="keyword">struct </span>HelloMessage { };</div>
<div class="line"></div>
<div class="line">    <span class="keyword">explicit</span> HelloWorld(<a class="code" href="classTheron_1_1Framework.html">Theron::Framework</a> &amp;framework) : Theron::<a class="code" href="classTheron_1_1Actor_a87c458ad24c3429da325ea6f207267f4.html#a87c458ad24c3429da325ea6f207267f4">Actor</a>(framework)</div>
<div class="line">    {</div>
<div class="line">        <a class="code" href="classTheron_1_1Actor_a8d5ef774be6470b8a1e8159f93aac07a.html#a8d5ef774be6470b8a1e8159f93aac07a">RegisterHandler</a>(<span class="keyword">this</span>, &amp;HelloWorld::Hello);</div>
<div class="line">    }</div>
<div class="line"></div>
<div class="line"><span class="keyword">private</span>:</div>
<div class="line"></div>
<div class="line">    <span class="keyword">inline</span> <span class="keywordtype">void</span> Hello(<span class="keyword">const</span> HelloMessage &amp;message, <span class="keyword">const</span> <a class="code" href="classTheron_1_1Address.html">Theron::Address</a> from)</div>
<div class="line">    {</div>
<div class="line">        printf(<span class="stringliteral">&quot;Hello world!\n&quot;</span>);</div>
<div class="line">    }</div>
<div class="line">};</div>
</div><!-- fragment --><p>Message handlers can be registered at basically any point in the lifetime of the actor. In particular they can safely be registered in the derived actor constructor, as well as from within other message handlers of the actor (themselves previously registered and then executed in response to received messages).</p>
<p>If a message handler is registered multiple times, it will be executed multiple times in response to received messages of its expected type. Each subsequent de-registration then removes just one of the multiple registrations.</p>
<p>One subtlety to be aware of is that message handlers aren't executed on receipt of messages of types <em>derived</em> from the message types expected by the handler. In order to handle derived message types, register separate handlers for those types - and call the handler registered for the base message type explicitly from the derived handler, if required.</p>
<div class="fragment"><div class="line"><span class="keyword">class </span>HelloWorld : <span class="keyword">public</span> <a class="code" href="classTheron_1_1Actor.html">Theron::Actor</a></div>
<div class="line">{</div>
<div class="line"><span class="keyword">public</span>:</div>
<div class="line"></div>
<div class="line">    <span class="keyword">struct </span>HelloMessage { };</div>
<div class="line">    <span class="keyword">struct </span>HowdyMessage : <span class="keyword">public</span> HelloMessage { };</div>
<div class="line"></div>
<div class="line">    <span class="keyword">explicit</span> HelloWorld(<a class="code" href="classTheron_1_1Framework.html">Theron::Framework</a> &amp;framework) : Theron::<a class="code" href="classTheron_1_1Actor_a87c458ad24c3429da325ea6f207267f4.html#a87c458ad24c3429da325ea6f207267f4">Actor</a>(framework)</div>
<div class="line">    {</div>
<div class="line">        <a class="code" href="classTheron_1_1Actor_a8d5ef774be6470b8a1e8159f93aac07a.html#a8d5ef774be6470b8a1e8159f93aac07a">RegisterHandler</a>(<span class="keyword">this</span>, &amp;HelloWorld::Hello);</div>
<div class="line">        <a class="code" href="classTheron_1_1Actor_a8d5ef774be6470b8a1e8159f93aac07a.html#a8d5ef774be6470b8a1e8159f93aac07a">RegisterHandler</a>(<span class="keyword">this</span>, &amp;HelloWorld::Howdy);</div>
<div class="line">    }</div>
<div class="line"></div>
<div class="line"><span class="keyword">private</span>:</div>
<div class="line"></div>
<div class="line">    <span class="keywordtype">void</span> Hello(<span class="keyword">const</span> HelloMessage &amp;message, <span class="keyword">const</span> <a class="code" href="classTheron_1_1Address.html">Theron::Address</a> from)</div>
<div class="line">    {</div>
<div class="line">        printf(<span class="stringliteral">&quot;Hello world!\n&quot;</span>);</div>
<div class="line">    }</div>
<div class="line"></div>
<div class="line">    <span class="keywordtype">void</span> Howdy(<span class="keyword">const</span> HowdyMessage &amp;message, <span class="keyword">const</span> <a class="code" href="classTheron_1_1Address.html">Theron::Address</a> from)</div>
<div class="line">    {</div>
<div class="line">        Hello(message, from);</div>
<div class="line">        printf(<span class="stringliteral">&quot;How y&#39;all doin?\n&quot;</span>);</div>
<div class="line">    }</div>
<div class="line">};</div>
</div><!-- fragment --><p>Another tricky subtlety is that the compiler may treat handlers that are exactly identical as the same function, in optimized builds. The following example shows this confusing effect:</p>
<div class="fragment"><div class="line"><span class="keyword">class </span>HelloWorld : <span class="keyword">public</span> <a class="code" href="classTheron_1_1Actor.html">Theron::Actor</a></div>
<div class="line">{</div>
<div class="line"><span class="keyword">public</span>:</div>
<div class="line"></div>
<div class="line">    <span class="keyword">struct </span>HelloMessage { };</div>
<div class="line"></div>
<div class="line">    <span class="keyword">explicit</span> HelloWorld(<a class="code" href="classTheron_1_1Framework.html">Theron::Framework</a> &amp;framework) : Theron::<a class="code" href="classTheron_1_1Actor_a87c458ad24c3429da325ea6f207267f4.html#a87c458ad24c3429da325ea6f207267f4">Actor</a>(framework)</div>
<div class="line">    {</div>
<div class="line">        <a class="code" href="classTheron_1_1Actor_a8d5ef774be6470b8a1e8159f93aac07a.html#a8d5ef774be6470b8a1e8159f93aac07a">RegisterHandler</a>(<span class="keyword">this</span>, &amp;HelloWorld::HelloOne);</div>
<div class="line">        <a class="code" href="classTheron_1_1Actor_a8b85886531b76f0e6aa9b46004ff6bb0.html#a8b85886531b76f0e6aa9b46004ff6bb0">IsHandlerRegistered</a>(<span class="keyword">this</span>, &amp;HelloWorld::HelloTwo);   <span class="comment">// May returns true, in some optimized builds.</span></div>
<div class="line">    }</div>
<div class="line"></div>
<div class="line"><span class="keyword">private</span>:</div>
<div class="line"></div>
<div class="line">    <span class="keywordtype">void</span> HelloOne(<span class="keyword">const</span> HelloMessage &amp;message, <span class="keyword">const</span> <a class="code" href="classTheron_1_1Address.html">Theron::Address</a> from)</div>
<div class="line">    {</div>
<div class="line">        printf(<span class="stringliteral">&quot;Hello world!\n&quot;</span>);</div>
<div class="line">    }</div>
<div class="line"></div>
<div class="line">    <span class="keywordtype">void</span> HelloTwo(<span class="keyword">const</span> HelloMessage &amp;message, <span class="keyword">const</span> <a class="code" href="classTheron_1_1Address.html">Theron::Address</a> from)</div>
<div class="line">    {</div>
<div class="line">        printf(<span class="stringliteral">&quot;Hello world!\n&quot;</span>);</div>
<div class="line">    }</div>
<div class="line">};</div>
</div><!-- fragment --><dl class="tparams"><dt>Template Parameters</dt><dd>
  <table class="tparams">
    <tr><td class="paramname">ActorType</td><td>The derived actor class. </td></tr>
    <tr><td class="paramname">ValueType</td><td>The message type accepted by the handler. </td></tr>
  </table>
  </dd>
</dl>
<dl class="params"><dt>Parameters</dt><dd>
  <table class="params">
    <tr><td class="paramname">actor</td><td>Pointer to the derived actor instance. </td></tr>
    <tr><td class="paramname">handler</td><td>Member function pointer identifying the message handler function. </td></tr>
  </table>
  </dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>True, if the registration was successful. Failure may indicate out-of-memory. </dd></dl>

</div>
</div>
    </td>
  </tr>
</table>
</div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated by &#160;<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.8.5
</small></address>
</body>
</html>
